Skip to main content

Docusaurus + Cloudflare Pages 字體載入失敗診斷與修正指南

一、現象證據​

  • 電腦版 Chrome 看起來字體正常
  • 手機版打開網站，字體消失，恢復到默認系統字體
  • 刪除手機瀏覽器快取後，還是看不到正確字體
  • 實際技術檢驗，確認字體資源存在，能正常打開

二、根本原因分析​

分類原因說明
1電腦版看到是「快取假象」，不是現場載入結果
2字體資源路徑配置錯誤
3未正確將 font-family 套用到頁面元素上
4Cloudflare Pages 伺服器對 font/woff2 資源送出 MIME Type 有效，因此沒有變成網路失敗問題

三、測試步驟​

  1. 手機打開網站，直接連線文件 URL：

    • https://網址/font/字體名.woff2
    • 看到亂碼（binary data），表示正常載入。

  2. 用手機瀏覽器 Developer Tools（選設備打開、或通過第三方工具），查看 Network > Fonts 資料，確認有 200 OK 返回

  3. 刪除誤定路徑與錯誤給定 font-face：

    • Docusaurus 中的 /static/ 目錄內容，在網站上會是直接 / 格式載入（不要有 /static/ 前置）。

四、正確組製 font-face 模板​

@font-face {
  font-family: 'Anton';
  src: url('/font/Anton-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

@font-face {
  font-family: 'Noto Sans TC';
  src: url('/font/NotoSansTC-Regular.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

五、設定全局 font-family​

body {
  font-family: 'Noto Sans TC', sans-serif;
}

h1, h2, h3 {
  font-family: 'Anton', sans-serif;
}

六、完整修正流程​

  1. 修正 font.css / custom.css 路徑
  2. 確保所有 @font-face 展示配置正確
  3. 確保路徑中沒有 /static/
  4. 設定 body 或頁面元素 font-family
  5. npm run build
  6. 重新上傳 Cloudflare Pages
  7. 手機全新瀏覽器瀏覽（必要可清除定頁快取）

結論：真正對體網站成效，不是看電腦機 F12 效果，而是手機等實際設備打開之後，实际診斷下結果。